'\"macro stdmacro
.\"
.\" Copyright (c) 2000-2004 Silicon Graphics, Inc.  All Rights Reserved.
.\"
.\" This program is free software; you can redistribute it and/or modify it
.\" under the terms of the GNU General Public License as published by the
.\" Free Software Foundation; either version 2 of the License, or (at your
.\" option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
.\" or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
.\" for more details.
.\"
.\"
.TH PMIECONF 5 "PCP" "Performance Co-Pilot"
.SH NAME
\f3pmieconf\f1 \- generalized pmie rules and customizations
.SH DESCRIPTION
The pmieconf file formats are used by the
.BR pmieconf (1)
tool as a way to generalize
.BR pmie (1)
rule sets such that they can be easily configured for different systems and
different environments.
There are two completely different (although closely related) file formats
discussed here, namely ``pmieconf-rules'' and ``pmieconf-pmie''.
.PP
The directory
.B $PCP_VAR_DIR/config/pmieconf
contains information about all the default system
.B pmie
generalized rules and variables, including default values for all variables.
These files are in the pmieconf-rules format.
Although new pmieconf-rules files can be added, the files in this directory
should never be changed.
Instead, use the
.B pmieconf
utility to change variable values in the
.B pmie
configuration file.
.PP
The pmieconf-pmie format allows site specific customizations of the rules
contained in pmieconf-rules files and their associated variables.
The pmieconf-pmie format is generated by
.B pmieconf
and should not be edited by hand.
This generated file is in the
.B pmie
format, with some additional information held at the head of the file \- thus,
the pmieconf-pmie format is a superset of the
.B pmie
file format (extended to hold customizations to the generalized rules, but
also containing the actual performance rules for
.B pmie
to evaluate) which can also be parsed by
.B pmie
(all extensions are hidden within comments, and are thus meaningless to
.B pmie
itself).
.PP
The file
.B $PCP_VAR_DIR/config/pmieconf/config.pmie
contains local system settings for
.B pmieconf
configurable variables.
The variable settings in this file replace the default values specified in
.BR $PCP_VAR_DIR/config/pmieconf/*/* .
.SH PMIECONF-PMIE SYNTAX
All rule customization lines in a valid pmieconf-pmie specification
are prefixed by ``//'' and are located at the head of the file \-
this allows files containing a pmieconf-pmie specification to be
successfully parsed by
.BR pmie .
A pmieconf-pmie must always have the first line in the form:
.sp
.nf
    // pmieconf-pmie \f2version\f1 \f2pmieconf_path\f1
.fi
.sp
The
.I version
specifies which version of the pmieconf-pmie syntax should be used to
parse this file.
Currently the only supported version is 1.  The
.I pmieconf_path
specifies the path to the pmieconf-rules files which were used, by
.BR pmieconf ,
to generate this file.  This is discussed in the
.BR pmieconf (1)
man page (see the
.B \-r
option).
.PP
The remainder of the specification consists of one line entries for each
of the modified variables.  The syntax for each line is:
.sp
.nf
    // \f2rule_version\f1 \f2rule_name\f1 \f2rule_variable\f1 = \f2value\f1
.fi
.sp
The
.I rule_version
and
.I rule_name
are used to identify the rule with which to associate the customization.
These are followed by the
.I rule_variable
name (i.e. the variable of rule
.I rule_name
which has been changed)
for which the new
.I value
is to be used.
.PP
A pmieconf-pmie specification must be terminated with the ``end'' keyword.
This is used by
.B pmieconf
to distinguish where the customizations ends, and the actual
.B pmie
rule component begins.
.SH PMIECONF-PMIE EXAMPLE
The following example is a valid pmieconf-pmie format file, as generated by
.BR pmieconf .
In order to make changes by hand which are preserved by
.BR pmieconf ,
see the comments contained in the generated file (below) as to where such
changes should be made.
.sp
.nf
    // pmieconf-pmie 1 $PCP_VAR_DIR/config/pmieconf
    // 1 memory.exhausted delta = "4 minutes"
    // 1 memory.exhausted enabled = yes
    // 1 memory.exhausted pcplog_action = yes
    // end
    //
    // --- START GENERATED SECTION (do not change this section) ---
    //     generated by pmieconf on:  [DATESTAMP]
    //

    // 1 memory.exhausted
    delta = 4 minutes;
    some_host (
        ( avg_sample (swap.pagesout @0..9 ) ) > 0 &&
        30 %_sample swap.pagesout >= 5
    ) -> shell 10 min "$PCP_BINADM_DIR/pmpost Severe demand for real memory" \\
            " %vpgsout/s@%h";

    // --- END GENERATED SECTION (changes below will be preserved) ---
.fi
.sp
.PP
To see how this all works, you can generate this file as follows:
.sp
.nf
    # cat \- | pmieconf \-f /tmp/pmieconf.out \\
        \-r $PCP_VAR_DIR/config/pmieconf/memory:$PCP_VAR_DIR/config/pmieconf/global
    modify memory.exhausted delta "4 minutes"
    modify memory.exhausted enabled yes
    modify memory.exhausted pcplog_action yes
    ^D
    #
.fi
.sp
Then verify that the generated file is a valid
.B pmie
configuration file using:
.sp
.nf
    # pmie \-C /tmp/pmieconf.out
.fi
.sp
This parses the file, and then exits after reporting any syntax errors.
Now replace \-C with \-v (above), and watch
.B pmie
do its work!
.SH PMIECONF-RULES SYNTAX
A pmieconf-rules specification consists of a number of separate data objects
which together form a complete rule specification (note that a specification
may span multiple files and even multiple subdirectories).
Each object must have an
.I identifier
string and a data
.IR type ,
followed by an (optional) list of
.IR attribute s.
.PP
The generic specification of a pmieconf-rules object is thus:
.sp
.nf
    \f2type\f1 \f2identifier\f1 [ \f2attribute\f1 = \f2value\f1 ]* ;
.fi
.sp
The set of valid
.IR type s
is: "rule" (rule definition), "string" (arbitrary, double-quote enclosed
string), "double", "integer", "unsigned", "percent" (real number between 0
and 100), "hostlist" (space separated list of host names), "instlist" (space
separated list of metric instance names), and the four
.B pmie
action types, namely
"print", "shell", "alarm", and "syslog".
.PP
Rule names use the ``.'' character to introduce the concept of a rule group,
e.g. "memory.exhausted" associates this rule with the "memory" group.
.B pmieconf
can operate at either the level of rule groups or individual rules.
The group name "global" is reserved and may not be used with any rule.
.PP
Usually when an object is created it is associated with the current rule.
However, if an object's name is preceded by the reserved group name "global",
then that object is visible to all rules.
.PP
The set of valid
.IR attribute s
is: "help" (descriptive text about this object), "modify" (\f2value\f1 is
yes/no, flags whether
.B pmieconf
should allow changes), "enabled" (\f2value\f1 is yes/no, flags whether this is
on or off - only meaningful for rules and actions), "display" (yes/no - flags
whether
.B pmieconf
should show this object), "default" (\f2value\f1 determined by \f2type\f1, and
is the default value for this object), and specific to objects of rule type
are the "version", "predicate", and "enumerate" attributes.  "version" and
"predicate" are fairly self explanatory ("predicate" must equate to a valid
.B pmie
rule when expanded), but "enumerate" requires further discussion.
.PP
The "enumerate" clause is useful when you wish to generate multiple, similar
.B pmie
rules from a single predicate.
This is most useful for rule definitions wishing to use the "some_inst"
clause in the
.B pmie
language across multiple hosts.
For a rule to use these together, it must be certain that the
instance list is the same on all of the monitored hosts.
This is rarely true, so the "enumerate" attribute allows us to generate
multiple rules, expanded over variables of either type "instlist" or "hostlist".
These variables make up the value for the "enumerate" attribute \- which is
a space-separated list of "instlist" or "hostlist" variable names.
.PP
Objects can be incorporated into other object definitions using the
$\f2identifier\f1$ syntax.  See the example later for more insight into
how this is useful.
.PP
When
.B pmieconf
is generating the
.B pmie
configuration file, it looks at each enabled rule with N enabled
actions (where N > 0) and expands the string:
.sp
.nf
    // "version" \f2identifier\f1
    delta = $delta$;
    "predicate" -> $threshold$ $action1$ & ... & $actionN$ ;
.fi
.sp
The delta, threshold, and action variables are defined globally
(using the "global" keyword) for all rules, but can, of course,
be changed at the level of an individual rule or rule group.
.SH PMIECONF-RULES EXAMPLE
The following is an example of a single pmieconf-rules specification,
showing a number of different aspects of the language discussed above.
The example defines a rule ("memory.exhausted") and a string ("rule").
.sp
.nf
    rule    memory.exhausted
            default = "$rule$"
            predicate =
    "some_host (
        ( avg_sample (swap.pagesout $hosts$ @0..9 ) ) > 0 &&
        $pct$ %_sample swap.pagesout $hosts$ @0..9 >= $threshold$
    )"
            enabled = yes
            version = 1
            help    =
    "The system is swapping modified pages out of main memory to the
    swap partitions, and has been doing this on at least pct of the
    last 10 evaluations of this rule.
    There appears to be insufficient main memory to meet the resident
    demands of the current workload.";

    string  rule
            default = "Severe demand for real memory"
            modify  = no
            display = no;
.fi
.sp
Note that for the above rule to be complete, "threshold" and "pct" would
also need to be defined - for the full expression of this rule, refer to
.IR $PCP_VAR_DIR/config/pmieconf/memory/exhausted .
.SH FILES
.PD 0
.TP 10
.IR $PCP_VAR_DIR/config/pmieconf/ */*
generalized system resource monitoring rules
.TP 10
.I $PCP_VAR_DIR/config/pmieconf/config.pmie
default super-user settings for system resource monitoring rules
.TP 10
.I $HOME/.pcp/pmie/config.pmie
default user settings for system resource monitoring rules
.PD
.SH SEE ALSO
.BR pmie (1)
and
.BR pmieconf (1).
